<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link
      href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono&family=IBM+Plex+Sans:wght@400;700&display=swap"
      rel="stylesheet"
    />
    <script
      type="module"
      src="https://js.withorbit.com/orbit-web-component.js"
    ></script>
    <title>Orbit Documentation</title>

    <style type="text/css">
      html {
        font-family: "IBM Plex Sans", Menlo, Consolas, monospace;
        color: #222;
      }
      h1,
      h2 {
        color: #333;
      }
      h2 {
        margin-top: 3rem;
      }
      body {
        margin: 2rem;
        max-width: 800px;
      }
      p,
      li {
        max-width: 600px;
        line-height: 1.4;
      }

      code {
        background-color: #eaeaea;
        padding: 0 0.1em;
      }

      pre,
      code {
        font-family: "IBM Plex Mono", monospace;
      }
      pre {
        background-color: #f0f0f0;
        margin: 0 0 0 -2rem;
        padding: 1rem 2rem;
        overflow: auto;
        font-size: 80%;
      }

      @media screen and (max-width: 400px) {
        body {
          margin: 1rem;
        }
      }

      .colorParagraph code.color {
        padding: 0em 0.2em;
        font-weight: bold;
      }
    </style>
  </head>
  <body>
    <h1>Orbit Documentation</h1>

    <p>
      Orbit lets you interleave recurring prompts into your writing. When used
      well, these prompts can help people reliably remember what they read,
      understand complex topics more easily, and stay connected to ideas over
      time.
    </p>
    <p>
      This page assumes you're familiar with the general idea;
      <a href="https://withorbit.com">click here</a> for more background on
      Orbit.
    </p>

    <h2>Getting started</h2>

    <p>
      Orbit's designed to work anywhere on the web. At the moment, you can embed
      Orbit using a
      <a href="https://www.webcomponents.org">Web Component</a> which can be
      used in any HTML page. Setup is easy: add one
      <code>&lt;script&gt;</code> tag, then you can use special
      <code>&lt;orbit-reviewarea&gt;</code> and
      <code>&lt;orbit-prompt&gt;</code> tags anywhere on the page to insert
      prompts. Here's an example:
    </p>
    <pre id="exampleListing">
&lt;html&gt;
  &lt;head&gt;
    &lt;script type="module" src="https://js.withorbit.com/orbit-web-component.js"&gt;&lt;/script&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;orbit-reviewarea color="red"&gt;
      &lt;orbit-prompt
        question="What's the working name for Andy's experimental mnemonic medium platform?"
        answer="Orbit"
      &gt;&lt;/orbit-prompt&gt;
      &lt;orbit-prompt
        question="What kind of quantum gate is this?"
        question-attachments="https://docs.withorbit.com/toffoli.png"
        answer="A Toffoli gate."
      &gt;&lt;/orbit-prompt&gt;
      &lt;orbit-prompt
        question="Given a right triangle with legs of length $a$ and $b$, what is the length of hypotenuse $c$?"
        answer="$$c = \sqrt{a^2 + b^2}$$"
      &gt;&lt;/orbit-prompt&gt;
    &lt;/orbit-reviewarea&gt;
  &lt;/body&gt;
&lt;/html&gt;</pre
    >

    <p>Here's a live demo of the review area that code would produce:</p>
    <orbit-reviewarea color="red" debug id="reviewArea">
      <orbit-prompt
        question="What's the working name for Andy's experimental mnemonic medium platform?"
        answer="Orbit"
      ></orbit-prompt>
      <orbit-prompt
        question="What kind of quantum gate is this?"
        question-attachments="https://docs.withorbit.com/toffoli.png"
        answer="A Toffoli gate."
      ></orbit-prompt>
      <orbit-prompt
        question="Given a right triangle with legs of length $a$
      and $b$, what is the length of hypotenuse $c$?"
        answer="$$c = \sqrt{a^2 +
      b^2}$$"
      ></orbit-prompt>
    </orbit-reviewarea>

    <script>
      const colorIndex = Math.floor(Math.random() * 12);
      const colorName = [
        "red",
        "orange",
        "brown",
        "yellow",
        "lime",
        "green",
        "turquoise",
        "cyan",
        "blue",
        "violet",
        "purple",
        "pink",
      ][colorIndex];
      const listingNode = document.getElementById("exampleListing");
      listingNode.innerHTML = listingNode.innerHTML.replace(
        /"red"/,
        `"${colorName}"`,
      );
      document.getElementById("reviewArea").setAttribute("color", colorName);
    </script>

    <p>
      That's it! You can publish that web page as it is. Your readers will be
      prompted to sign into Orbit if they haven't already. The prompts they
      answered will be saved to their account. Next time they have prompts ready
      for review, they'll be notified by email and provided a link to the Orbit
      review interface, which displays prompts aggregated from all the sites
      they've visited.
    </p>

    <p>
      You don't have to do anything special to register your site, though in the
      future I'll allow you to register URLs so that you can see reader
      analytics.
    </p>

    <p>
      While that example can be published as it is, read on to learn more about
      how to configure Orbit for your web site.
    </p>

    <h2>Configuring review areas</h2>

    <h3>Prompts support simple formatting</h3>

    <p>
      The <code>question</code> and <code>answer</code> attributes support a
      subset of Markdown formatting. In particular, you can use inline styling
      and multiple paragraphs. You can use LaTeX by enclosing inline math in $
        symbols and display blocks in $$ symbols, as in the example above. Reserved HTML characters (like &gt;, &amp;, and &lt;) will need to be escaped using <a href="https://en.wikipedia.org/wiki/Character_encodings_in_HTML">entity encodings</a>: for instance, &gt; is written as <code>&amp;gt;</code>.
    </p>

    <p>
      You can attach an image (PNG, GIF) to the question or answer by specifying
      a URL using the <code>question-attachments</code> or
      <code>answer-attachments</code> attribute, as in the example above. You
      may omit the <code>question</code> or <code>answer</code> attributes if an
      attachment is present. Note that you must supply an absolute URL, not a
      relative URL like <code>/toffoli.png</code>. Your image will be cached on
      Orbit's servers, and changes to its contents may not propagate reliably. If
      you need to update an image, you should also change its URL.
    </p>
    <p>
      Support for videos, multiple images, and custom layouts is forthcoming.
      Please <a href="mailto:andy@andymatuschak.org">let me know</a> if these
      absences are blocking you to help me prioritize.
    </p>

    <h3>Review areas have colors</h3>

    <p class="colorParagraph">
      You'll notice that review areas have a <code>color</code> attribute. Each
      site can choose the color it would like its Orbit prompts to be. Then,
      when readers are reviewing prompts from multiple sites, they'll see your
      prompts rendered in the color you chose—providing a little bit of context.
      The supported color values are:
      <code class="color" style="background-color: #ff5252">red</code>,
      <code class="color" style="background-color: #fa863d">orange</code>,
      <code class="color" style="background-color: #e0a642">brown</code>,
      <code class="color" style="background-color: #fac800">yellow</code>,
      <code class="color" style="background-color: #8fd43a">lime</code>,
      <code class="color" style="background-color: #63d463">green</code>,
      <code class="color" style="background-color: #52dada">turquoise</code>,
      <code class="color" style="background-color: #65c6f6">cyan</code>,
      <code class="color" style="background-color: #72aef8">blue</code>,
      <code class="color" style="background-color: #ad89fb">violet</code>,
      <code class="color" style="background-color: #d071ef">purple</code>, and
      <code class="color" style="background-color: #f56bb5">pink</code>.
    </p>

    <h3>Orbit relies on page metadata</h3>

    <p>
      When readers review one of your prompts in their follow-up sessions, Orbit
      provides context by displaying a link to the page containing those
      prompts. The interface may also display progress grouped by "source"
      pages. It's important to make sure that metadata is correct. Here's the
      information Orbit extracts from your page and how to customize it:
    </p>
    <ul>
      <li>
        <strong>Page title:</strong> Orbit will use the <code>og:title</code>
        <a href="https://ogp.me">OpenGraph</a> meta tag if present on your page.
        If that's absent, it will use the value of the
        <code>&lt;title&gt;</code> tag.
      </li>
      <li>
        <strong>Canonical URL:</strong> If your content can be viewed from
        several URLs, it's important to inform Orbit of the canonical URL so
        that it can group prompts correctly. Orbit will use the
        <a href="https://en.wikipedia.org/wiki/Canonical_link_element"
          >canonical link element</a
        >
        if available; otherwise, it will use the page URL.
      </li>
      <li>
        <strong>Site title:</strong> Orbit's interface may group prompts from
        different pages of your site. To label that group, it will use the
        <code>og:site_name</code> <a href="https://ogp.me">OpenGraph</a> meta
        tag if present.
      </li>
    </ul>
    <p>
      Here's an example <code>&lt;head&gt;</code> demonstrating these values:
    </p>
    <pre>
&lt;head&gt;
    &lt;title&gt;Obesity - Our World in Data&lt;/title&gt;
    &lt;link rel="canonical" href="https://ourworldindata.org/obesity"&gt;
    &lt;meta property="og:title" content="Obesity"&gt;
    &lt;meta property="og:site_name" content="Our World in Data"&gt;
&lt;/head&gt;</pre
    >

    <h3>You can include multiple review areas on a single page</h3>

    <p>
      It's common to use several <code>&lt;orbit-reviewarea&gt;</code> tags on
      the same page, interleaving them every few hundred words. Orbit currently
      assumes that all the review areas which appear on a web page should be
      considered part of the same single piece of content. This works fine for
      long-form content but will produce confusing results in e.g. a blog layout
      which displays many posts' contents on one big page. Orbit will eventually
      allow finer-grained configuration here; please
      <a href="mailto:andy@andymatuschak.org">let me know</a> if your site needs
      this to help me prioritize.
    </p>

    <p>
      If you have several <code>orbit-reviewarea</code>s in one page, you can
      avoid repeating the <code>color</code> attribute on each of them by
      specifying the color in the page's <code>&lt;head&gt;</code> tag, like
      this:
    </p>
    <pre>
&lt;head&gt;
  &lt;meta property=&quot;orbit:color&quot; content=&quot;violet&quot; /&gt;
&lt;/head&gt;</pre
    >

    <h3>The current prompt type is meant for memory practice</h3>

    <p>
      The existing prompt interface and scheduler are tuned to questions which
      help people remember and internalize what they read. I believe it's also
      possible to use Orbit to prompt reflection, self-authorship, texts which
      extend over time, and so on. Please
      <a href="mailto:andy@andymatuschak.org">let me know</a> if you're
      interested in exploring these use cases; we can figure out how to extend
      the interface in a way that suits your text.
    </p>

    <h3>Testing your prompts</h3>
    <p>
      While you're writing and revising your prompts, you may want to enable a
      "test mode" which won't save of your actions to your account. To do this,
      append <code>?orbitDebug</code> to your URL. So for instance, if you're
      viewing <code>http://you.com/test</code>, point your browser at
      <code>http://you.com/test?orbitDebug</code>. If the URL already has a
      <code>?</code> in it, add <code>&orbitDebug</code> instead, e.g.
      <code>http://you.com/test?id=4</code> becomes
      <code>http://you.com/test?id=4&orbitDebug</code>. And if your web server
      redirects <code>http://you.com/test</code> to
      <code>http://you.com/test/</code>, you'll want to visit
      <code>http://you.com/test/?orbitDebug</code>.
    </p>

    <h2>Writing well with Orbit</h2>

    <p>
      By introducing Orbit into your writing, you're not just "adding on" a set
      of flashcards: you're learning to write in a new medium which integrates
      prose and lightweight exercises. The system only works as well as the
      prompts you write, and it's deceptively difficult to write them well.
      You're essentially trying to take all the important ideas you've described
      in sentences and encode them into questions which, when the reader thinks
      about them, will reinforce the intended material.
    </p>

    <p>
      This topic ultimately deserves a small <em>Elements of Style</em>-like
      book. I've begun by creating a guide to writing good prompts for your own
      personal study practice:
      <em
        ><a href="https://andymatuschak.org/prompts"
          >How to write good prompts</a
        ></em
      >. Writing good prompts for other people is more challenging. Once I
      understand those considerations better, I'll write a follow-up guide on
      that topic. In the meantime, here are a few resources which might be
      useful:
    </p>

    <ul>
      <li>
        <a href="https://quantum.country">Quantum Country</a> is the first book
        written in this medium. Its prompts are a good initial demonstration.
      </li>
      <li>
        <a href="https://numinous.productions/ttft"
          >How can we develop transformative tools for thought?</a
        >
        discusses the medium at length and includes a
        <a href="https://numinous.productions/ttft/#improving-mnemonic-medium"
          >section</a
        >
        on this topic.
      </li>
      <li>
        I'm assembling working notes for a future guide
        <a
          href="https://notes.andymatuschak.org/z42J1vxsMjhkdbrqVfoqjiEesSzfaEqurBtoJ"
          >here</a
        >
      </li>
    </ul>

    <p>
      I'd like to be very involved in early writers' efforts with Orbit. I'm
      happy to workshop prompts, review drafts, talk technique, etc. Please
      <a href="mailto:andy@andymatuschak.org">email me</a>.
    </p>

    <p>🙇👋, Andy</p>
  </body>
</html>
